Skip to content

refactor(repo)!: adopt snake_case resource and kebab-case module labels - #310

Merged
aghassemlouei merged 5 commits into
google:mainfrom
digitalresistor:refactor/terraform-naming-convention
Oct 20, 2026
Merged

aghassemlouei merged 5 commits into
google:mainfrom
digitalresistor:refactor/terraform-naming-convention

Conversation

@digitalresistor

Copy link
Copy Markdown
Contributor

Description

Terraform labels in the code that Stellar Engine owns now follow the naming convention that upstream Cloud Foundation Fabric enforces, and CI enforces it with tflint.

  • Resource, data source, variable and output labels use snake_case, and module labels use kebab-case, matching Enable terraform_naming_convention in tflint GoogleCloudPlatform/cloud-foundation-fabric#3930.
  • Every renamed resource and module gets one of 80 new moved blocks, so existing deployments move the state instead of destroying and recreating the resources.
  • The renames cover all five stages under fast/stages-aw/, the blueprints under blueprints/, and the modules/organization-se/ and modules/private-service-connect/ modules.
  • The blueprint edits live in blueprints/il5/ for the directories that the blueprints/fedramp-high/ symlinks point to.
  • The modules/organization-se/logging.tf file uses the exact labels and moved blocks of the upstream organization module, so the upstream sync in [Feature Request] Sync the modules from upstream Cloud Foundation Fabric and keep them current #308 merges it cleanly.
  • The README examples of the cis-log-alerts, cis-log-metrics, cloud-scheduler, intrusion-detection-system and private-service-connect modules use kebab-case module labels.
  • The new tools/tflint.sh script lints every Terraform directory under fast/, blueprints/ and modules/. Its UPSTREAM_PENDING_SYNC list skips the 11 upstream-tracked module directories that still carry old labels, and [Feature Request] Sync the modules from upstream Cloud Foundation Fabric and keep them current #308 removes that list.
  • The script enforces only the naming rule for now, because the existing recommended preset reports 66 unrelated findings on main.
  • The new tflint CI job installs tflint v0.64.0 through terraform-linters/setup-tflint, verifies the release checksum, tests the runner and runs the tools/tflint.sh script. The tools/lint.sh script runs it too.
  • The docs/naming-convention.md guide and the .gemini/styleguide.md review guide document the convention and the moved block requirement.

Fixes #309

Breaking Changes

Blueprint outputs and one blueprint variable change names. State moves automatically, but forks that read these outputs or set this variable need to update. The ! in the title marks the change as breaking, so Release Please cuts a new major release.

Renamed Terraform labels to snake_case for resources and kebab-case for
modules. moved blocks migrate state, so plans show moves, not replacements.

Renamed blueprint outputs, old -> new:

blueprints/fedramp-high/cloud-run
  service-account -> service_account
blueprints/fedramp-high/gitlab
  gke-cluster -> gke_cluster
blueprints/il5/compute-engine, also blueprints/fedramp-high/compute-engine
  compute-engine-vm-instance -> compute_engine_vm_instance
  compute-engine-vm-instance-id -> compute_engine_vm_instance_id
  compute-engine-vm-internal_ip -> compute_engine_vm_internal_ip
  compute-engine-vm-internal_ips -> compute_engine_vm_internal_ips
  compute-engine-vm-service_account -> compute_engine_vm_service_account
  compute-engine-vm-service_account_email -> compute_engine_vm_service_account_email
blueprints/il5/dataflow, also blueprints/fedramp-high/dataflow
  dataflow-job -> dataflow_job
  gcs-bucket -> gcs_bucket
blueprints/il5/gke-hardened, also blueprints/fedramp-high/gke-hardened
  vpc-network -> vpc_network
  vpc-subnet_ids -> vpc_subnet_ids
  vpc-subnet_ips -> vpc_subnet_ips
blueprints/il5/shielded-vm-project, also blueprints/fedramp-high/shielded-vm-project
  shielded-vm-instance -> shielded_vm_instance
  shielded-vm-instance-id -> shielded_vm_instance_id
  shielded-vm-internal_ip -> shielded_vm_internal_ip
  shielded-vm-internal_ips -> shielded_vm_internal_ips
  shielded-vm-service_account -> shielded_vm_service_account
  shielded-vm-service_account_email -> shielded_vm_service_account_email

Renamed blueprint variable, old -> new:

blueprints/il5/gcs-project, also blueprints/fedramp-high/gcs-project
  bucket-name -> bucket_name

Rename bucket-name to bucket_name in your terraform.tfvars, and update
any scripts that run terraform output with the old names.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update

Deployment & Compliance Impact

  • Applicable Regimes:
    • US Region Restricted (e.g., Access Policy constraint)
    • FedRAMP Moderate
    • FedRAMP High
    • DoD IL4
    • DoD IL5
    • General / All
  • NIST 800-53r5 Controls: CM-2 baseline configuration and CM-3 configuration change control, through consistent labels and an enforced lint baseline. No control implementation changes.

Checklist

Code Quality & Reusability

  • My code adheres to the Maximize Reusability principle. I have not redefined common elements and have reused existing base configurations and modules where possible.
  • I have checked that no existing module or configuration in modules/ or fast/stages-aw/ can be leveraged for this change.
  • My code follows the established naming conventions outlined in docs/naming-convention.md.

Documentation

  • I have updated the README.md of the modified module or blueprint.
  • I have added/updated documentation for inputs (variables) and outputs.

Security

  • My change adheres to GCP security best practices and the principle of least privilege.
  • I have ensured compliance with the targeted regime (FedRAMP Moderate, FedRAMP High, IL4, IL5, etc.).

Testing

  • I have tested my changes locally.
  • I have included details of my testing in this PR.

Testing Performed

The checks below ran locally on the branch, and on an origin/main export where a comparison applies.

  • tflint v0.64.0 with the naming rule reports 148 unique violations on origin/main, and 152 when it counts the symlinked stage 2a file twice. On the branch, the tools/tflint.sh script checks 137 directories with no findings, and fails on a planted resource or module label.
  • The new tests/scripts/test_tflint.sh script passes 6 tests under bash 5 and the macOS bash 3.2, and skips when tflint is missing.
  • A python-hcl2 checker compares each changed directory with origin/main. All 84 moved blocks, which count the 4 that the symlinked log-metric-alerts.tf file adds to stage 2a, map a removed address to an existing one, and no address appears or disappears otherwise.
  • A full-address search of every old label finds no reference outside the from side of a moved block in .tf files, READMEs, samples, scripts/, docs/ and tests/.
  • terraform init -backend=false and terraform validate pass for all 27 changed roots on the branch and on origin/main, with Terraform 1.13.3. Stages 1 to 3 use a local stub for the billing provider alias that operators otherwise copy from the stage outputs.
  • terraform fmt -recursive -check passes.
  • bash tests/scripts/run_shell_tests.sh passes, and pytest passes 66 tests.
  • zizmor and actionlint report no findings for .github/workflows/ci.yml, and shellcheck passes for both new scripts.
  • tools/check_boilerplate.py reports the same 22 files on origin/main and on the branch, which chore(repo): fix repo-wide lint failures and make tools/lint.sh fail closed #286 addresses. tools/check_documentation.py fails on origin/main with an unknown fixture error, so the README tables changed only for the renamed outputs and the variable.
  • No test deployment exists yet, so no plan against real state ran. The moved blocks follow the pattern that upstream #3930 uses for the same renames.

…in stages

Rename the stage resource labels to snake_case and the CIS log metric and
alert module labels to kebab-case, matching the convention that upstream
Cloud Foundation Fabric enforces with tflint. Each renamed resource and
module has a moved block, so existing deployments move the state instead
of destroying and recreating the resources.
…abels

Rename blueprint resource, output, variable and local labels to snake_case
and module labels to kebab-case, with a moved block for every renamed
resource and module. The fedramp-high symlinks follow the il5 sources.

BREAKING CHANGE: Blueprint outputs such as compute-engine-vm-instance and
the il5/gcs-project bucket-name variable now use snake_case names. Update
terraform.tfvars files and scripts that read these outputs.
…ase modules

Use the labels and moved blocks of the upstream organization module in
organization-se/logging.tf, so the next upstream sync merges the file
cleanly. Rename the private-service-connect pkg_dev module to pkg-dev with
a moved block, and use kebab-case module labels in the README examples of
the Stellar Engine modules.
Add the upstream terraform_naming_convention rule to .tflint.hcl and a
tools/tflint.sh runner that checks every directory under fast, blueprints
and modules. The runner skips the modules that still carry pre-v55.4.0
upstream labels until the upstream sync renames them, and enforces only
the naming rule because the recommended preset still reports unrelated
findings. A new CI job and tools/lint.sh run it, and
shell tests cover the runner.
Describe the snake_case and kebab-case label rules and the moved block
requirement in docs/naming-convention.md, and add the rule to the review
styleguide.
@github-actions github-actions Bot added Framework - IL5 DoD Impact Level 5 (IL5) compliance regime and controls Framework - FedRAMP High FedRAMP High compliance regime and controls Scope - Fast Related to Fabric FAST deployment stages in the fast directory Scope - Blueprint Related to solution blueprints in the blueprints directory Scope - Modules labels Oct 20, 2026
@aghassemlouei

aghassemlouei commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

More than supportive of this but I think @Calvin-Cheng1 should at least be made aware since if we do this we might as well lint the codebase and issue a breaking change.

@digitalresistor

Copy link
Copy Markdown
Contributor Author

This is already marked as a breaking change with the ! in the PR title. It will cause a 5.x release to be created. Is there additional documentation that needs to be done here? I will note that the moved blocks at least take the onus off things for users that want to migrate to this new change for terraform runs.

@aghassemlouei aghassemlouei added Enhancement New feature or request Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent Level of Effort - Medium Moderate task requiring thought and testing; typically takes a couple of days to a week Scope - Module Related to reusable Terraform modules in the modules directory and removed Scope - Modules labels Oct 20, 2026

@aghassemlouei aghassemlouei left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No additional documentation is needed here since GEMINI.md already specifies snake_case for resources, data sources, variables, and outputs alongside kebab-case for modules. The 81 moved blocks cover state migration cleanly across the stages, blueprints, and custom modules, the tflint wrapper and test suite pass, and the breaking change marker in the title will surface the two renamed blueprint outputs (airflow_dag_gcs_prefix and gke_cluster_name) in the 5.0.0 release notes.

@aghassemlouei
aghassemlouei merged commit 813e0a8 into google:main Oct 20, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Enhancement New feature or request Framework - FedRAMP High FedRAMP High compliance regime and controls Framework - IL5 DoD Impact Level 5 (IL5) compliance regime and controls Level of Effort - Medium Moderate task requiring thought and testing; typically takes a couple of days to a week Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent Scope - Blueprint Related to solution blueprints in the blueprints directory Scope - Fast Related to Fabric FAST deployment stages in the fast directory Scope - Module Related to reusable Terraform modules in the modules directory

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Adopt the upstream Fabric naming convention for Terraform labels

2 participants